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Particle  Tracking  Model  (PTM)  in  the  SMS: 

I.  Graphical  Interface 


PURPOSE:  This  Dredging  Operations  and  Environmental  Research  (DOER)  Technical  Note 
(TN)  describes  the  graphical  interface  for  the  Particle  Tracking  Model  (PTM).  The  Coastal  Inlets 
Research  Program  (CIRP)  and  the  DOER  Program  are  jointly  developing  the  PTM.  The  PTM  is 
described  in  a  series  of  three  technical  notes.  This  technical  note,  Part  I,  describes  the  graphical 
user  interface  of  Version  1.0  of  PTM.  Part  II  (Demirbilek  et  al.  2005a)  provides  an  overview  of 
general  features  and  capabilities  of  PTM.  Part  III  (Demirbilek  et  al.  2005b)  is  a  tutorial  with 
examples.  The  PTM  has  been  developed  for  application  to  dredging  and  coastal  projects, 
including  dredged  material  dispersion  and  fate,  sediment  pathway  and  fate,  and  constituent 
transport.  A  technical  report  (MacDonald  and  Davies,  in  preparation)  provides  details  about  the 
theory  and  implementation  aspects  of  the  PTM. 

INTRODUCTION:  PTM  methodology  is  based  on  a  parcel  calculation  technique,  in  which 
parcels  represent  a  given  mass  of  sediment  subjected  to  the  same  forces  and  exhibiting  the  same 
kinematics  as  a  single  sediment  particle.  Each  parcel  has  its  own  set  of  attributes  (e.g.,  grain 
diameter,  specific  gravity),  which  influence  parcel  behavior  (entrainment,  transport,  settling). 
The  PTM  employs  a  Lagrangian  particle  tracking  technique  to  estimate  migration  of  sediment 
particles  as  influenced  by  the  hydrodynamic  forcing  inputs,  including  current  velocity  and  wave 
fields.  This  approach  compliments  the  Eularian  sediment  transport  and  morphological  models, 
and  can  provide  information  about  a  specified  subset  of  sediment  processes.  This  information 
may  be  applied  in  projects  without  the  more  resource-intensive  application  of  a  Eularian 
sediment  transport  model. 

PTM  inputs  are  unstructured  grid  bathymetry,  and  time  series  of  both  water  surface  elevation, 
current  velocity  fields,  and  waves  at  each  point  in  the  modeling  domain.  The  grid  bathymetry  is 
read  from  the  standard  IMS-ADCIRC  (ADvanced  CIRCulation  model;  see  Luettich  et  al.  (1992)) 
mesh  file.  The  water  surface  elevation  and  current  velocity  fields  are  read  from  files  written 
using  the  Generic  Model  Data  Format  standard  (XMDF;  see  Jones  et  al.  (2004)).  Optionally, 
PTM  also  supports  wave  model  or  field  data  at  grid  points  from  a  separate  (Cartesian)  grid. 
Wave  input  files  to  PTM  are  the  standard  STWAVE  (Steady-state  WAVE  transformation  model) 
output  files  (Smith  et  al.  2001).  In  addition  to  the  hydrodynamic  and  wave  input,  the  user 
specifies  sediment  sources,  sediment  properties,  and  model  parameters  to  run  PTM.  The  SMS 
interface  of  the  PTM  includes  commands  for  layout  of  the  model  inputs  including  sediment 
sources,  specification  of  the  numerical  parameters,  and  management  of  the  Eulerian  data  (grids 
and  solutions  of  ADCIRC  and  STWAVE).  Both  hydrodynamic  and  wave  inputs  are  mapped  to 
the  PTM-specific  computational  grid.  The  velocity  and  wave  fields  must  be  computed  or 
approximated  (if  desired)  prior  to  constructing  a  PTM  simulation  in  SMS.  Result  files  for  these 
fields  are  then  used  as  input  to  a  PTM  simulation. 
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PTM  I/O  FILES:  PTM  requires  five  input  files  (Figure  1).  These  are  the  model  parameters  file 
(*.pcf),  the  particle  source  file  (*. source),  the  native  sediments  file  (*. sediments),  the  ADCIRC 
Eulerian  grid  file  (*.grd  or  *.14),  and  the  flow  data  in  XMDF  format  (*.h5).  Two  other  optional 
file  types  containing  wave  data  and  particle  trap  definitions  may  also  be  specified.  The  model 
may  be  launched  from  inside  SMS,  in  which  case  the  parameter  file  can  be  built  through 
interface  prompts.  All  other  input  file  names  and  their  locations  are  specified  in  the  *.pcf  file, 
along  with  the  names  and  locations  of  model  output  files.  Alternatively,  the  model  can  also  be 
run  outside  of  SMS  using  the  parameter  file  as  a  command  line  argument.  In  this  case,  all  input 
files  must  already  exist. 


Required  input  files 

projname.  pcf 
projname.  source 
projname.  sediments 
projname.grd 
projname_dsets.  h5 
Optional  input  files 
projname.  wav 
projname.trap 


Figure  1.  Files  involved  in  a  PTM  simulation 

The  model  creates  two  types  of  output  files,  the  particle  and  Eulerian  mapped  output  files.  The 
particle  output  file  (*_parcels.h5)  contains  the  paths  and  locations  of  individual  parcels  at  each 
output  time,  along  with  attributes  of  those  parcels  such  as  their  characteristic  size,  speed,  source, 
and  index.  Parcel  attributes  that  may  be  saved  are  briefly  described  in  Table  1.  Eulerian  mapped 
data  are  output  to  the  *_map.h5  file  at  each  grid  location.  The  Eulerian  output  includes  wave 
parameters,  flow  values,  bedforms,  and  computed  mobility. 


PTM 


< 


Output  files 

projname _parcels.h5 
projname _  map .  h5 


Table  1 

Particle  Attributes  Resulting  from  PTM  Simulation 

Attribute 

Type 

Description 

Grain  size 

Static  -  floating  point 

Size  of  a  characteristic  particle 

Mobility 

Transient -floating  point 

Tendency  of  the  particle  to  move 

Elevation 

Transient  -  floating  point 

Elevation  of  the  particle  above  the  sediment  bed 

State 

Transient  -  integer 

=0  for  dormant  particle,  =1  for  moving  particle 

ID 

Static  -  integer 

Particle  ID 

Source 

Static  -  integer 

Particle  source  identifier 

Parcel  mass 

Static  -  floating  point 

The  total  mass  of  particle 

The  PTM  output  files  are  in  binary  format,  and  written  as  hdf5  files  in  XMDF  standard 
fhttp://www.wes. army.mil/ITL/XMDF).  These  files  allow  for  storing  large  simulations  in  a 
compressed  form  to  speed  up  data  processing  and  viewing,  and  ensuring  portability  of  the 
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compressed  data  across  different  computing  platforms.  The  binary  file  format  also  allows  users 
to  run  the  PTM  on  one  computing  platform  and  perform  post-processing  on  a  different 
computing  platform.  The  default  computing  platform  for  the  PTM  simulations  is  a  PC,  and  all  of 
these  tasks  can  be  performed  on  a  PC. 


PTM  INTERFACE:  The  PTM  interface  in  SMS  is  accessed  through  the  Particle  Module  '  of 
SMS.  User  assistance  for  SMS  is  available  through  the  “Help”  icon  within  SMS  and  the  SMS 
users  guide  (Zundel  2005).  A  general  description  of  the  interface  follows.  A  simulation  can  be 
initiated  by  choosing  the  New  Simulation  command  in  the  PTM  menu,  or  by  opening  an  existing 
simulation  using  either  an  SMS  project  (.spr)  file  or  a  PTM  program  control  file  (.pcf).  The  PTM 
uses  the  Map  Module  to  define  the  source  terms  for  particles,  and  may  use  the  Mesh  Module 


rca  to  visualize,  select,  and  possibly  convert  the  current  data.  PTM  also  utilizes  the  Cartesian 
Grid  Module  EH3  to  convert,  visualize,  and  select  wave  input  data. 


The  PTM  interface  primarily  consists  of  the  PTM  menu  and  various  sub-menus  in  the  Particle 
Module,  and  the  PTM  coverage  in  the  Map  Module.  The  Particle  Module  is  used  to  specify  user 
input  and  create  the  *.pcf  file  and  the  Map  Module  is  used  to  define  the  particle  source  terms. 
This  document  describes  the  standard  components  of  the  PTM  interface.  It  is  recommended  that 
the  user  become  familiar  with  other  modules  of  SMS  to  fully  exploit  the  many  intricacies  and 
features  of  the  PTM  interface. 


PTM  menu.  The  PTM  menu  and  commands  are 
listed  and  described  in  Figure  2  and  Table  2, 
respectively. 


I 

k  Ne 


Window  Help 


New  Simulation 
Model  Control 


Run  Model 


Figure  2.  PTM  Menu 


Table  2 

PTM  Menu  Commands 

Command 

Functionality 

New  Simulation 

Creates  a  new  PTM  simulation.  A  simulation  includes  a  set  of  particle  sources,  sediment 
conditions,  run  parameters,  and  the  corresponding  particle  paths  computed  by  PTM 
once  the  model  has  been  executed. 

Model  Control 

Brings  up  the  Model  Control  dialog  to  specify  model  simulation  parameters  for  the 
present  simulation. 

Run  Model 

Brings  up  a  dialog  to  allow  users  to  select  the  executable  of  PTM  to  run  with  the  present 
simulation.  As  the  model  runs,  a  dialog  monitors  progress  of  the  model  and  gives  the 
user  status  messages.  After  the  run  is  complete,  the  spatial  solutions  are  read  in  for 
analysis  and  visualization. 

Specifying  simulation  parameters.  The  PTM  simulation  dialogue  stores  all  the  model 
parameters  and  input  files  used  in  a  simulation.  To  specify  these  parameters  the  user  selects  the 
Model  Control  command  from  the  PTM  menu,  which  invokes  the  PTM  Model  Control  Dialog. 
This  dialogue  consists  of  six  separate  pages  (Figure  3-9),  discussed  below: 
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•  Computational  parameters  dialog  page 
(Figure  3).  This  page  allows  the  user  to  select 
computational  methods  and  parameters  from 
the  available  list  of  capabilities. 
Computational  methods  include  choosing 
whether  particles  will  be  distributed  by 
weight  or  by  grain  size,  whether  Eulerian 
interpolation  will  use  the  van  Rijn  (1984  and 
1993)  or  PTM  method,  whether  the  particle 
centroid  will  be  computed  by  the  Rouse 
(1939)  or  van  Rijn  method  and  whether 
advection  will  use  the  2D  or  quasi-3D 
method.  User-specified  computational 
parameters  in  the  Model  Control  dialogue 
box  include  the  specification  of  a  minimum 
cut-off  depth,  water  temperature,  salinity, 
transport  factor,  and  diffusion  parameters. 
The  minimum  cut-off  depth  refers  to  the 
minimum  water  depth  for  which  a  particle 
will  be  tracked.  The  minimum  depth  is  used 
to  limit  calculations  at  near-zero  depths; 
typically  this  is  set  to  0.01  m,  but  may  need 
to  be  set  lower  if  working  on  very  fine  scale 
or  laboratory  problems.  If  a  particle  moves 
into  a  region  of  the  domain  with  a  water 
depth  lower  than  the  cutoff  depth,  the  particle 
is  considered  inactive  until  water  level  rises 
enough  to  increase  the  depth  above  the  cutoff 
depth.  The  user  also  specifies  how  often  the 
shear,  bedforms,  and  mobility  should  be 
recomputed.  The  user  is  referred  to  the 
technical  report  (MacDonald  and  Davies,  in 
preparation)  for  a  description  of  these 
methods  and  appropriate  application. 

•  Hydrodynamic,  sediment,  and  source  input 
dialog  page  (Figure  4).  This  page  is  used  to 
specify  input  files  for  bathymetry,  flow 
(current  and  water  surface  elevation),  and 
native  sediment  parameters.  This  box  is  also 
used  to  define  particle  sources.  As  noted 
above,  the  model  requires  a  Eulerian  grid  to 
define  the  bathymetry,  native  sediments, 
water  surface,  and  the  velocity  field.  If  these 
files  exist  in  the  appropriate  format,  they  can 
be  accessed  directly  without  loading  the  grid 


Figure  3.  Computational  parameters  page  of 
PTM  Model  Control  Dialog 


Figure  4.  Hydrodynamic,  sediment,  and  source 
inputs  page  of  PTM  Model  Control 
Dialog 
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into  SMS.  If  the  files  do  not  exist  in  the  appropriate  format,  SMS  can  be  used  to  convert 
existing  Eulerian  data  to  the  correct  format  using  the  Create  Files  from  Data  button.  This 
button  displays  the  Create  PTM  external  input  files  dialog  (Figure  5). 

The  top  section  of  this  dialog  is  used  to 
select  the  Eulerian  grid  geometry  file. 

Clicking  on  the  Choose  button  displays 
a  list  of  the  Eulerian  objects  that  have 
been  loaded  into  SMS.  This  could  be  a 
finite  element  mesh,  or  a  curvilinear 
grid,  or  a  scattered  triangular  mesh 
from  hydrodynamic  models.  The  only 
limitation  is  that  the  object  must  have 
bathymetric,  water  surface,  and  current 
data  defined  in  a  data  set  for  each 
computation  node  in  the  grid.  These 
data  will  be  converted  to  the 
appropriate  PTM  structure  within  the 
SMS  interface.  The  PTM  solution/ 
output  time  units  are  also  specified  in 
the  interface.  The  SMS  converts  from 
days,  hours,  or  minutes  into  seconds  as 
required  for  PTM  calculations.  As 
shown  in  the  top  part  of  the  panel 
(Figure  5),  the  PTM  reads  in  ADCIRC- 
format  fort.  14  file  and  creates  a  PTM 
geometry  file  in  the  same  format.  In 
the  flow  files  section  of  the  dialog,  the 
user  may  select  ADCIRC-format  for 
current  and  water  elevation  files  to  be 
saved  as  PTM  input  files.  The  SMS 
creates  the  PTM  input  files  when  the 
user  clicks  the  OK  button.  The  bottom 
panel  allows  the  user  to  create  the  native  sediments  file.  This  file  includes  the  characteristic 
grain  sizes  (in  millimeters)  of  the  native  bed.  A  negative  value  of  dgo  indicates  a  hard-bottom 
bed  and  the  value  supplied  would  represent  the  roughness  factor  (millimeters).  Native 
sediments  are  not  resuspended  in  the  PTM  because  they  are  not  a  particle  source,  but  they  are 
used  to  compute  roughness,  bed  forms,  and  active  layer  mixing,  thereby  affecting  turbulence 
and  particle  mobility. 

•  Time  control  dialog  page  (Figure  6).  The  time  control  page  of  the  PTM  Model  Control  dialog 
is  used  to  specify  simulation  dates  and  the  time-step  size.  Input  parameters  are:  start  date/time, 
end  date/time,  computation  time-step,  output  interval,  and  hydrodynamics  start  time.  The 
hydrodynamic  solution  must  start  at  or  before  the  starting  PTM  simulation  date/time,  and  must 
contain  valid  data  for  the  entire  PTM  simulation  period.  Guidance  for  selecting  the  simulation 
time-step  is  provided  in  the  PTM  technical  report  (MacDonald  and  Davies,  in  preparation).  In 


Create  PTM  External  Input  Files  [x] 


Figure  5.  Dialog  to  create  input  files  from  Eulerian  grid 
in  SMS 
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another  dialog  box,  the  user  specifies  time 
periods  of  the  particle  sources.  These  time 
periods  must  be  included  in  the  computational 
time  range  defined  in  the  Time  Control  dialog. 

Output  control  dialog  page  (Figure  7).  The 
Output  Options  page  allows  the  user  to 
specify  which  model  results  to  save  to  the 
output  files  during  the  PTM  simulation.  PTM 
creates  two  solution  files.  One  stores  the 
particle  data  (Lagrangian),  and  the  other 
stores  the  mapped  Eulerian  data.  They  are 
named  by  adding  on  to  the  simulation  name. 
The  top  portion  of  the  page  defines  which 
particle-related  data  sets  are  saved  to  the 
“SimulationNamejparticles.hS”  file.  The 
bottom  portion  of  this  dialogue  allows  the 
user  to  select  data  to  be  mapped  back  to  the 
Eulerian  grid  and  saved  to  the 
“SimulationName file.  The  user 
also  specifies  how  often  each  data  type  should 
be  saved. 

Wave  input  dialog  page  (Figure  8).  This  page 
is  similar  to  the  hydrodynamic,  sediment,  and 
source  inputs  page  described  previously.  It 
allows  the  user  to  specify  a  wave  field  input 
file  for  the  PTM  simulation.  The  user 
specifies  the  origin  and  orientation  of  the  grid. 
If  the  grid  is  loaded  into  SMS,  the  “ From 
STWAVE  Grid”  button  will  fill  in  the  origin 
and  angle  based  upon  the  grid.  In  the  lower 
portion  of  the  dialog,  the  user  can  input 
output  file  name  (*.wav)  and  time  stamp  for 
the  wave  input  file. 

Trap  control  dialog  page  (Figure  9).  The  trap 
control  page  allows  the  user  to  specify  the 
timing  control  of  the  polygonal  traps  defined 
in  the  PTM  coverage.  The  user  can  also 
specify  whether  the  traps  will  retain  the 
particles  as  they  arrive,  and  if  they  do  not 
retain  them,  whether  to  count  particles  that 
enter  the  trap  multiple  times  as  a  single 
instance  or  multiple  instances.  The  PTM 
technical  report  provides  more  detail  on  using 
traps  in  PTM  simulations. 


Figure  6.  Time  Control  page  of  PTM  model 
control  dialog 


Figure  7.  Output  control  page  of  PTM  model 
control  dialog 
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PTM  Model  Control 


Hydro.  Sediment,  and  Source  inputs  j  Time  Control 

Computational  Parameters  |  Output  Options  Waves  j  Traps 

HR  Use  waves 
Geomr 


retry 


From  STWAVE  Grid 


Origin  |o!o 

Angle  {ON  y-axis  to  North)  |0.@ 


p“ 


Solution  data  (.wav) 

M 

Start  Date/Time 
Time  between  spectra: 
Number  of  Spectra  in  File 


1 1 2/30/1  m  12::W::OOAM 


00::00::00 


Help  |  OK 

Cancel 

Figure  8.  Wave  control  page  of  PTM  model 
control  dialog 


PTM  Model  Control 


Hydro,  Sediment,  and  Source  inputs  j  Time  Control 

Computational  Parameters  |  Output  Options  Traps 


Start  time:  1 12/1 5/2004  10::00::00AM 
Stop  time:  1 12/1 5/2004  1 1 : : 00: : 00  F'M 
H  Closed  T  rap  (particles  do  not  leave  trap) 
t~  Only  count  particles  once  per  simulation 


Help 


OK 


Cancel 


Figure  9.  Trap  control  page  of  the  PTM  model 
control  dialog 


Specifying  particle  sources.  Particle  sources  are  defined  as  attributes  on  nodes  and  arcs  (Zundel 
et  at.  1998;  Zundel  2005)  in  the  PTM  coverage  in  the  Map  Module  i.e.,  PTM  sediment 
sources  are  defined  at  a  point  or  along  a  path.  The  positions  and  attributes  of  each  time-varying 
source  are  managed  in  the  map  module  of  SMS  through  the  Feature  Objects /Attributes 
command.  The  source  attributes  can  be  managed  and  edited  using  the  Feature  Attributes 
command  in  the  map  module.  The  user  can  create  feature  points  in  the  map  module,  and  by 
double-clicking,  assign  attributes  to  any  feature  point  to  define  it  as  a  particle  source.  Figures  10- 
13  illustrate  the  SMS-generated  dialogs  (tables)  for  each  of  the  source  types.  Each  row  of  the 
table  represents  a  point  in  time  describing  the  life  of  the  source.  For  times  between  rows,  each 
column  of  data  is  linearly  interpolated  from  the  rows  before  and  after  it.  The  first  column  of  the 
table  includes  the  date  and  time.  The  table  also  includes  a  central  position  (x,y)  for  the 
generation  of  particles,  elevation,  and  characteristic  size.  The  position  of  each  particle  generated 
actually  varies  across  a  specified  radius  (both  horizontal  and  vertical).  Further,  the  size  of  the 
characteristic  grain  of  the  particle  varies  according  to  a  specified  grain  size  distribution, 
characterized  by  the  standard  deviation  of  the  sediments.  For  details,  see  MacDonald  and  Davies 
(2005).  Particle  source  types  include: 

•  Point  source  of  certain  mass  rate  (Figure  10).  A  mass  rate  point  source  produces  particles  at 
a  specified  rate  over  time.  Each  row  in  the  table  defines  the  point  source  central  location  at 
the  time  specified  in  the  first  column.  Point  source  locations  between  the  times  specified  in 
any  two  adjacent  rows  are  interpolated  between  the  locations  specified  in  each  row.  The 
generation  rate,  characteristic  grain  size,  and  other  attributes  also  vary  with  time.  This 
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method  of  particle  release  can  be  used,  for  example,  to  represent  effluent  loss  from  a  pipeline 
that  is  moved  intermittently. 


Figure  10.  Mass  rate  point  source  attribute  table 


•  Point  source  with  instant  mass  (Figure  1 1).  An  instant  mass  source  creates  an  entire  group  of 
particles  at  specific  points  in  time.  The  times  are  specified  in  the  first  column  of  each  row 
and  the  remaining  columns  control  the  amount  of  mass,  the  mass  in  each  particle,  and  the 
other  particle  attributes.  As  with  mass  rate  sources,  the  particle  initial  positions  are 
distributed  randomly  around  the  central  location  to  allow  for  a  natural  variability.  This 
method  of  particle  release  can  be  used,  for  example,  to  represent  release  from  a  split-hull 
barge  during  dredged  material  placement. 


Point  Source  Propertie& 


Instant  Mass 


Source  Type: 

Point  Name:  J  Instant  Mass  Source 


E 


Date /Time 

X 

Y 

Elevation 

Parcel  Mass 

Horiz,  Radius 

Vert.  Radius 

Mass 

Size 

Deviation 

Density 

Cm] 

Cm] 

Cm) 

(kg) 

Cm] 

Cm) 

(kg) 

Cmm) 

(kg/mA3) 

10/6/2004  12:00:00  PM 

4764,0 

2633,0 

3,0 

2,0 

1,0 

1.0 

130,0 

0.2 

0.8 

2650,0 

11/30/2004  12:35:45  PM  JL 

Help  |  OK  |  Cancel 


Figure  1 1 .  Instant  mass  point  source  attribute  table 
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•  Vertical  line  sources  at  a  planar  point  (Figure  12).  Point  sources  may  be  used  to  represent  a 
set  of  vertical  line  sources.  At  the  top  of  the  dialog,  the  user  specifies  the  number  of  bins  in 
the  line  source  and  the  maximum  height  above  the  bottom  that  particles  will  be  generated. 
To  the  right  of  this  information,  the  user  enters  the  rate  of  particle  generation  for  each 
vertical  segment  as  a  percentage  of  the  total  mass  of  particles  generated.  The  vertical  line  is 
segmented  into  equal  increments  (height  divided  by  the  number  of  bins).  The  table  at  the 
bottom  again  defines  the  timing  of  the  particle  generation  (the  first  column),  the  central 
position  of  the  particle  generation  (second  and  third  columns),  and  the  particle  attributes  as 
described  above  (columns  4-10).  Particles  are  distributed  linearly  along  the  line  and 
according  to  a  Gaussian  distribution  around  the  line.  This  source  can  be  used,  for  example, 
to  simulate  vertical  distribution  of  sediment  released  into  the  water  column  from  a  moving 
dredge. 


Figure  12.  Vertical  line  at  a  point  source  attribute  table 

•  Horizontal  line  source  (Figure  13).  A  horizontal  line  source  is  situated  along  a  straight  line 
with  two  end  points  having  a  constant  elevation.  Particles  are  generated  evenly  (uniformly) 
along  this  straight  line.  The  line  can  move  over  time.  Each  row  defines  the  position  of  the 
line  at  a  particular  time,  which  is  specified  in  the  first  column.  The  positions  of  particles  are 
defined  in  columns  2-7.  The  remaining  columns  define  the  particle  attributes  as  defined 
above. 
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■  Line  Source  Properties 


Arc  Type:  |  Source  T~[ 

Source  Name:  | 


f*  Show  Coordinates  in  Spreadsheet 


Date/Time 

XI 

Y1 

Elevation  1 

X2 

Y2 

Elevation2 

Parcel  Mass 

Horiz.  Radius 

Vert.  Radius 

Rate 

Size 

Deviation 

Density 

(m) 

(m) 

(m) 

(m) 

(m) 

(m) 

(kg) 

(m) 

(m) 

(kg/s) 

(mm) 

(kg/m^3) 

10/6/2004  6:00:00  ...  Z 

3575.0 

3845.0 

10.0 

3575.0 

1570.0 

10.0 

2.0 

1.0 

1.0 

0.000022 

0.025 

0.8 

2650.0 

10/6/2004  7:00:00...  Z 

3575.0 

3845.0 

10.0 

3575.0 

1570.0 

10.0 

2.0 

1.0 

1.0 

0.000022 

0.025 

0.8 

2650.0 

10/6/2004  7:00:01...  Z 

3575.0 

3845.0 

10.0 

3575.0 

1570.0 

10.0 

2.0 

1.0 

1.0 

0.0 

0.025 

0.8 

2650.0 

11/30/200412:34:...  j| 

Help  |  OK  |  Cancel  | 


Figure  13.  Horizontal  line  source  attribute  table 


Visualizing  PTM  solutions.  The  principal  output  from  PTM  is 
a  series  of  particle  locations  over  time  and  attributes  of  those 
particles  at  each  time  (the *  *_particle.h5  file).  The  SMS  includes 
tools  for  visualizing  the  particle  paths.  These  tools  reside  in  the 

Particle  Module  %  .  The  solution  file  is  read  into  SMS  using 
the  File|Open  command.  Particle  data  sets  and  attributes  appear 
under  the  name  of  the  simulation  in  the  Project  Explorer  dialog 
(tree  window)  in  SMS  (Zundel  2005)  as  shown  in  Figure  14.  In 
this  example,  PTM  output  (see  Figure  14)  consists  of  particle 
sources  (which  stay  constant  for  all  times),  particle  states 
(active  or  inactive,  i.e.,  mobile  or  immobile),  and  particle 
velocities.  The  latter  two  change  from  one  time-step  to  another. 

The  user  can  select  an  active  data  set  in  the  upper  portion  of  the 
tree,  and  an  active  time-step  to  display  in  the  lower  portion  of 
the  tree. 

•  Particle  display  options  (Figures  15  and  16).  The  display 
options  in  the  SMS  interface  allow  users  to  specify  which 
particles  to  display  and  how  they  should  be  displayed. 

Options  include  displaying  the  particle  at  a  point  in  time, 
the  particle  path  (over  the  whole  particle  life),  and/or  a 
portion  of  the  path  (specified  as  a  time  length).  These 
options  are  depicted  in  Figures  15  and  16.  The  display 
options  are  shown  in  Figure  15.  The  three  toggles  allow  the  user  to  set  the  display  status  of 
the  particles,  the  particle  tails  (portion  of  the  particle  path),  and  the  particle  paths.  By 
clicking  on  the  small  buttons,  the  user  can  change  the  line  thicknesses  and  colors,  and  set  the 
symbol  to  be  used  for  the  particle.  Particles  and  particle  tails  can  be  color  coded  to  display 
their  attributes  by  choosing  to  color  particles  based  on  the  data  sets  read  from  the  solution 
file.  In  the  lower  right  side  of  the  dialog,  the  user  can  choose  to  filter  the  number  of  particles 
to  be  displayed. 


Data  Tree 


Figure  14.  Particle  data  sets  in 
the  project  browser 
and  the  time-steps 


10 


ERDC  TN-D0ER-D4 
July  2005 


Figure  15.  Particle  module 
display  options 


Display  Options 


General  |  2D  Mesh  |  Boundary  Grid  |  Cartesian  Grid  |  Scatter  |  Map  1  1 D 

Contour  Options  |  Vectors  |  Cascade  Grid  Particles 


U  1^  Particle  path  lines 


Particle  Display  Filter 
Number  of  particles:  443 

Display  every 


particle 


Begin  with  particle:  0 
End  with  particle:  --7 


Help 


OK 

Cancel 

Mesh  Module  water  surface  elevation  (63)  3600.000 


Figure  16.  Particle  heads,  paths,  and  tails 
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Figure  16  is  an  example  display  of  PTM  output.  The  particles  and  their  tails  are  colored 
based  on  the  velocity  of  the  particle.  The  variation  in  path  color  demonstrates  the  change  in 
velocity  over  the  particle  path,  and  the  length  of  the  tail  shows  how  far  the  particle  has 
traveled  in  the  last  half  hour.  The  user  specifies  this  value.  The  complete  paths  are  shown  as 
thinner,  brown  lines. 

+ 

•  Particle  selection.  The  particle  selection  tool  *  **  can  be  used  to  select  a  specific  particle  or 
group  of  particles.  If  a  single  particle  is  selected,  SMS  displays  the  exact  value  from  the 
current  data  set  or  attribute.  In  other  words,  if  the  particle  velocity  is  selected  in  the  Project 
Explorer,  and  a  user  selects  a  particle,  the  computed  velocity  for  that  particle  is  displayed. 
The  tool  also  provides  information  about  the  number  of  particles  in  a  specific  area  and  the 
average  value  of  the  data  set  for  the  particles  in  that  area. 


Data  menu.  Several  tools  that  can  assist  with  visualization  are 
available  through  the  SMS  particle  module  data  menu  shown  in 
Figure  17.  These  are: 

o  Create  data  sets.  This  command  allows  the  user  to  generate 
additional  data  sets  for  each  particle  throughout  the  time  range 
of  the  simulation.  The  particles  and  their  tails  can  be  colored 
based  on  the  values  in  these  data  sets.  Figure  18  illustrates  the 
dialog  provided  to  create  these  data  sets.  The  user  selects 
which  data  sets  to  create,  and  a  name  for  the  computed  data 
set. 


Figure  17.  Particle  data 
menu 


Figure  18.  Create  Data  Set  options  dialog 


o  Film  loop.  This  command  allows  users  to  animate  the  progress  of  the  displayed  particles 
through  time  and  saves  the  output  to  an  avi  file. 
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o  Compute  grid  datasets.  This  command  allows  users  to  convert  the  particle  data  in  a 
region  to  a  set  of  cells  in  a  Cartesian  grid.  For  example,  the  user  may  want  to  visualize 
the  concentration  of  suspended  particles  over  a  Eulerian  domain.  By  defining  a  grid  in  the 
grid  module,  the  user  can  select  this  command,  and  SMS  computes  the  concentration 
based  on  the  number  of  particles  in  each  cell  of  the  grid,  and  the  cumulative  particle 
masses  as  a  ratio  with  the  depth  and  size  of  the  cell.  Additional  data  sets  that  are 
computed  include  the  number  of  particles  from  each  source  in  each  cell  and  the  average 
deposition  thickness  in  the  cell. 

SUMMARY:  Various  features,  tools,  and  analysis  capabilities  outlined  in  this  document  are 
designed  to  enhance  the  ability  of  engineers  to  run  the  PTM  in  the  SMS.  This  technical  note  is 
applicable  to  Version  1.0  of  PTM,  and  provides  an  overview  of  the  main  features  of  the  interface 
necessary  for  accurate  and  efficient  usage  of  the  model.  The  PTM  and  SMS-based  interface  will 
evolve  as  the  model  is  developed  and  applied  in  engineering  applications.  Therefore,  the 
interface  of  the  PTM  will  undergo  revision.  Feedback  and  suggestions  from  users  on  design, 
implementation,  and  usage  of  the  present  version  of  the  PTM  interface  are  welcome. 

POINTS  OF  CONTACT:  This  technical  note  was  written  by  Dr.  Zeki  Demirbilek,  email: 
Zeki.Demirbilek@erdc.usace.army.mil),  Tel:  601-634-2834,  Fax:  601-634-4033;  Mr.  Jarrell 
Smith  (Jarrell.Smith@erdc.usace.army.mil)  of  the  U.S.  Army  Engineer  Research  and 
Development  Center  (ERDC),  Coastal  and  Hydraulics  Laboratory;  Dr.  Alan  Zundel 
(zundel@bvu.edu)  and  Mr.  Russell  Jones  (rjones@bvu.edu)  of  Brigham  Young  University;  and 
Dr.  Neil  MacDonald  (nmacdonald@piengr.com)  and  Mr.  Michael  Davies  (mdavies@piengr.com) 
of  Pacific  International  Engineering,  PLLC.  Questions  about  this  technical  note  should  be 
addressed  to  Dr.  Zeki  Demirbilek  or  to  the  Program  Manager  of  the  Dredging  Operations  and 
Environmental  Research  (DOER)  Program,  Dr.  Robert  M.  Engler  (601-634-3624, 
Robert.M.Engler@erdc.usace.army.mil).  This  technical  note  should  be  referenced  as  follows: 

Demirbilek,  Z.,  Smith,  J.,  Zundel,  A.,  Jones,  R.,  MacDonald,  N.,  and  Davies,  M. 
(2005).  “Particle  Tracking  Model  (PTM)  in  the  SMS:  I.  Graphical  Interface,” 
Dredging  Operations  and  Environmental  Research  Technical  Notes  Collection  (ERDC 
TN-DOER-D4),  U.S.  Army  Engineer  Research  and  Development  Center,  Vicksburg, 

MS.  An  electronic  copy  of  this  TN  is  available  from 
http://el.erdc.usace.army.mil/dots/doer. 
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